package com.twitter.home_mixer.product.scored_tweets.candidate_pipeline

import com.twitter.home_mixer.product.scored_tweets.feature_hydrator.IsExtendedReplyFeatureHydrator
import com.twitter.home_mixer.product.scored_tweets.feature_hydrator.ReplyFeatureHydrator
import com.twitter.home_mixer.product.scored_tweets.feature_hydrator.RetweetSourceTweetFeatureHydrator
import com.twitter.home_mixer.product.scored_tweets.filter.RetweetSourceTweetRemovingFilter
import com.twitter.home_mixer.product.scored_tweets.gate.MinCachedTweetsGate
import com.twitter.home_mixer.product.scored_tweets.model.ScoredTweetsQuery
import com.twitter.home_mixer.product.scored_tweets.param.ScoredTweetsParam.CachedScoredTweets
import com.twitter.home_mixer.product.scored_tweets.param.ScoredTweetsParam.CandidatePipeline
import com.twitter.home_mixer.product.scored_tweets.query_transformer.TimelineRankerInNetworkQueryTransformer
import com.twitter.home_mixer.product.scored_tweets.response_transformer.ScoredTweetsInNetworkResponseFeatureTransformer
import com.twitter.product_mixer.component_library.candidate_source.timeline_ranker.TimelineRankerInNetworkCandidateSource
import com.twitter.product_mixer.component_library.model.candidate.TweetCandidate
import com.twitter.product_mixer.core.functional_component.candidate_source.BaseCandidateSource
import com.twitter.product_mixer.core.functional_component.feature_hydrator.BaseCandidateFeatureHydrator
import com.twitter.product_mixer.core.functional_component.filter.Filter
import com.twitter.product_mixer.core.functional_component.gate.Gate
import com.twitter.product_mixer.core.functional_component.transformer.CandidateFeatureTransformer
import com.twitter.product_mixer.core.functional_component.transformer.CandidatePipelineQueryTransformer
import com.twitter.product_mixer.core.functional_component.transformer.CandidatePipelineResultsTransformer
import com.twitter.product_mixer.core.model.common.identifier.CandidatePipelineIdentifier
import com.twitter.product_mixer.core.pipeline.PipelineQuery
import com.twitter.product_mixer.core.pipeline.candidate.CandidatePipelineConfig
import com.twitter.timelineranker.{thriftscala => t}
import com.twitter.timelines.configapi.decider.DeciderParam
import javax.inject.Inject
import javax.inject.Singleton

/**
 * Candidate Pipeline Config to fetch in-network tweets from Timeline Ranker's Recycled source
 */
//当然可以。这段代码定义了 ScoredTweetsInNetworkCandidatePipelineConfig 类，它配置了一个专门的候选管道，
// 用于从 Twitter 的时间线排名器（Timeline Ranker）获取网络内的推文。下面我们来详细分析这个类中的关键函数和它们的逻辑。
@Singleton
class ScoredTweetsInNetworkCandidatePipelineConfig @Inject() (
  timelineRankerInNetworkCandidateSource: TimelineRankerInNetworkCandidateSource,
  replyFeatureHydrator: ReplyFeatureHydrator)
    extends CandidatePipelineConfig[
      ScoredTweetsQuery,
      t.RecapQuery,
      t.CandidateTweet,
      TweetCandidate
    ] {
  //为这个候选管道配置提供了一个唯一的标识符，用于在系统中标识和引用。
  override val identifier: CandidatePipelineIdentifier =
    CandidatePipelineIdentifier("ScoredTweetsInNetwork")
  //定义了一个决策参数，用于确定是否启用这个管道。这允许基于配置或运行时条件来启用或禁用管道。
  override val enabledDeciderParam: Option[DeciderParam[Boolean]] =
    Some(CandidatePipeline.EnableInNetworkParam)
  //定义了管道中使用的门控逻辑。例如，MinCachedTweetsGate 确保在处理查询之前有足够的缓存推文。
  override val gates: Seq[Gate[ScoredTweetsQuery]] = Seq(
    MinCachedTweetsGate(identifier, CachedScoredTweets.MinCachedTweetsParam)
  )
  //指定了候选源，即从哪里获取候选推文。这里使用了 timelineRankerInNetworkCandidateSource 作为来源。
  override val candidateSource: BaseCandidateSource[t.RecapQuery, t.CandidateTweet] =
    timelineRankerInNetworkCandidateSource
  //定义了如何转换查询。查询转换器将 ScoredTweetsQuery 转换为可由候选源理解的格式。
  override val queryTransformer: CandidatePipelineQueryTransformer[
    ScoredTweetsQuery,
    t.RecapQuery
  ] = TimelineRankerInNetworkQueryTransformer(identifier)
  //在过滤候选推文之前，定义了一系列特征水合器。这些水合器为推文添加额外的信息或特征。
  override val preFilterFeatureHydrationPhase1: Seq[
    BaseCandidateFeatureHydrator[PipelineQuery, TweetCandidate, _]
  ] = Seq(RetweetSourceTweetFeatureHydrator)
  //定义了一系列过滤器，用于筛选候选推文。例如，RetweetSourceTweetRemovingFilter 用于移除特定类型的推文。
  override def filters: Seq[Filter[ScoredTweetsQuery, TweetCandidate]] = Seq(
    RetweetSourceTweetRemovingFilter
  )
  //在过滤之后，又定义了一系列特征水合器，例如 IsExtendedReplyFeatureHydrator 和 replyFeatureHydrator，进一步丰富推文的特征。
  override val postFilterFeatureHydration: Seq[
    BaseCandidateFeatureHydrator[PipelineQuery, TweetCandidate, _]
  ] = Seq(IsExtendedReplyFeatureHydrator, replyFeatureHydrator)
  //定义了如何从候选源转换推文特征。这有助于从原始数据源提取并转换特定的特征。
  override val featuresFromCandidateSourceTransformers: Seq[
    CandidateFeatureTransformer[t.CandidateTweet]
  ] = Seq(ScoredTweetsInNetworkResponseFeatureTransformer)
  //提供了一个结果转换器，它将候选源的结果转换为系统中使用的 TweetCandidate 对象。
  override val resultTransformer: CandidatePipelineResultsTransformer[
    t.CandidateTweet,
    TweetCandidate
  ] = { sourceResult => TweetCandidate(id = sourceResult.tweet.get.id) }
}
